<HTML>
<!--This file created 14/3/01 8:53 AM by Claris Home Page version 3.0-->
<HEAD>
   <TITLE>Batch Architect Package</TITLE>
   <META NAME=GENERATOR CONTENT="Claris Home Page 3.0">
   <X-CLARIS-WINDOW TOP=42 BOTTOM=757 LEFT=4 RIGHT=534>
   <X-CLARIS-TAGVIEW MODE=minimal>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</HEAD>
<BODY bgcolor="#FFFFCC">
<H2> 
  <TABLE BORDER=0 CELLPADDING=4>
    <TR> 
      <TD>
<P><img src="splash.gif" width="164" height="64"></P></TD>
      <TD> <H2>Batch Architect package for the Mesquite system</H2></TD>
    </TR>
  </TABLE>
</H2>

<H4>David Maddison &amp; Wayne Maddison</H4>

<P>August 2005</P>

<P>This package of modules supplies basic importing and exporting
services to Mesquite.</P>

<UL>
  <LI><A HREF="#overview">Overview</A></LI>
  <LI><A HREF="#installation">Installation</A></LI>
  <LI><A HREF="#features">Features</A>
    <ul>
      <li><a href="#embf">Export Matrices &amp; Batch Files</a></li>
      <li><a href="#ebf">Export Batch Files</a></li>
      <li><a href="#batchtemplates">Batch Templates</a></li>
      <li><a href="#codesnippets">Code Snippets</a></li>
      <li><a href="#chartresults">Chart Results via Instruction File</a></li>
    </ul>
  </LI>
  <LI><A HREF="#examples">Examples</A></LI>
  <LI><A HREF="#citation">Citation</A></LI>
</UL>

<H3><A NAME=overview></A>Overview</H3>

<P>This package automates the generation of files with repeated elements as well 
  as the processing of files with repeated records.</P>
<P>One can ask Mesquite to build a &quot;batch&quot; file that can serve as a 
  command file for another program such as PAUP* that does repetitive analyses. 
  For example, one might simulate 100 matrices under a particular model of evolution, 
  and for each of these matrices, include an entry in a batch file that asks PAUP 
  to analyze that matrix, saving tree files for the matrix. At the same time, 
  another batch file might be created that could be used to ask another program 
  to read in, sequentially, each tree file, and conduct a synthetic analysis on 
  them. </P>

<H3><A NAME=installation></A>Installation</H3>

<P>To install the basic Batch Architect package, the "batchArch" directory must 
  be installed in the "mesquite" directory within "Mesquite Folder". It should 
  be present in a basic Mesquite installation.</P>

<H3><A NAME=features id="features"></A>Features</H3>
<h4><a name="embf"></a>Export Matrices &amp; Batch Files</h4>
<p>This feature, in the Batch Architect submenu in the Analysis menu, will export 
  multiple matrices and one or more associated batch files. </p>
<p>In choosing this feature, you will first be led through as serious of dialog 
  boxes in which you will choose how the matrices are to be created. Following 
  your choosing, the Export Matrices &amp; Batch Files dialog box will be presented:</p>
<p align="center"><img src="emb1.gif" width="336" height="356"></p>
<p>In this dialog box you are to specify the base name to be used both for the 
  matrices and in the batch file template system. For example, in the example 
  shown, 10 matrices will be created, with names &quot;SimMatrix1&quot;, &quot;SimMatrix2&quot;, 
  &quot;SimMatrix3&quot;, and so on. </p>
<p>The file names may have extensions added (e.g., &quot;.nex&quot;), depending 
  upon the matrix format to be used (the matrix format is specified in the batch 
  file template). The extension will be added automatically by Mesquite.</p>
<p>In this dialog you will most importantly also select the batch template to 
  use. A batch template specifies exactly how the batch file or files produced 
  will be structured. To examine or edit the template, use the Edit Templates 
  button. </p>
<p>Some batch templates contain code that requires &quot;<a href="#codesnippets">code 
  snippets</a>&quot; to be defined. If code snippets are needed by a template, 
  they will be listed in the dialog box. If some are needed but unavailable, the 
  list will appear in red and note them as unavailable:</p>
<p align="center"><img src="snippetNeeded.gif" width="320" height="48"> </p>
<p>You can define or edit snippets uing the Edit Snippets button.</p>
<p>Some batch templates require a tree to be chosen by the user; if so, and you 
  have not yet chosen a tree, &quot;TREE NEEDED&quot; will appear in red in the 
  box beside the Choose Tree button:</p>
<p align="center"><img src="treeNeeded.gif" width="248" height="24"></p>
<p>You can then use the Choose Tree button to choose your tree.</p>
<h4><a name="ebf"></a>Export Batch Files</h4>
<p>This is similar to the Export Matrices &amp; Batch Files feature expect that 
  no matrices are exported. This can be used to generate batch files for already 
  existing matrices, for example, or to automate processes other than the analyses 
  of matrices.</p>
<h4><a name="batchtemplates"></a>Batch Templates</h4>
<P>Batch templates contain the instructions telling Mesquite how to construct 
  the batch files. They are managed in the Batch Template Manager window, which 
  allow ones to create, duplicate, edit, rename, or delete templates:</P>
<P align="center"><img src="templateManager.gif" width="275" height="237"></P>
<P>You can also load templates from template files; this allows you to move templates 
  between copies of Mesquite. For example, if you create a template on one computer, 
  it will be stored as a single text file in the BatchTemplates in the Mesquite_Prefs 
  directory in the Mesquite_Support_Files directory on your disk. You can then 
  move that file to another computer, and load it into Mesquite on that computer 
  using the Load button. </P>
<P>Selecting a template in the Batch File Template Manager and pressing &quot;View&quot; 
  (if it is a pre-defined template) or &quot;Edit...&quot; (if it is a user-defined 
  template) will bring forth the Batch Template Editor, in which the template 
  can be viewed or edited:</P>
<P align="center"><img src="batchtemplate.gif" width="348" height="408"></P>
<P>See the page on <a href="batchtemplates.html">Designing Batch Templates</a> 
  for details on the formats used. Batch templates can be edited using the submenu 
  in Mesquite's Edit menu, or from the Export Matrices &amp; Batch Files or Export 
  Batch Files dialog boxes.</P>
<P>The pre-defined templates can be viewed and duplicated, but not renamed or 
  edited. Their duplicates can be renamed and edited.</P>
<h4><a name="codesnippets"></a>Code Snippets</h4>
<P>Code snippets are designed as file-specific elements that are to be used in 
  place of tagged elements in the batch templates. For example, if in a batch 
  template the following text appeared:</P>
<pre>   exec setParameterValues;
   &lt;snippet&gt;search command&lt;/snippet&gt;
   display all;</pre>
<p>then within the Mesquite file you could store a code snippet called &quot;search 
  command&quot; whose contents would be inserted in place of the above text when 
  the batch file was created. If the text of &quot;search command&quot; was</p>
<pre>   hsearch nreps=100 addseq=random swap=tbr;</pre>
<P>then the batch file, when written, would contain</P>
<pre>   exec setParameterValues;
   hsearch nreps=100 addseq=random swap=tbr;
   display all;

</pre>
<p>Batch templates can be edited using the Batch File Templates submenu in Mesquite's 
  Edit menu, or from the Export Matrices &amp; Batch Files or Export Batch Files 
  dialog boxes.</p>
<h4><a name="chartresults"></a>Chart Results via Instruction File</h4>
<P>If you have a text file on disk containing tab-delimited data, you can design 
  a Mesquite Instruction file that will give Mesquite enough information about 
  the data file to allow Mesquite to read it. See <a href="instructions.html">Instructions 
  File Format</a> for details about the way Mesquite Instruction files are to 
  be structured.</P>
<P>Some of the batch templates distributed with Mesquite have instruction files 
  defined within them.</P>
<H3><a name=examples></a>Examples</H3>
<p>See the <a href="../../../docs/mesquite/RandomSimul/RandomSimul.html">Simulations 
  and Randomizations</a> page of the Mesquite manual for examples.</p>
<H3>Citation</H3>

<P> Maddison, D.R., &amp; W.P. Maddison. 2005. Batch Architect: automation of 
  simulations and replicated analyses. A package of modules for Mesquite. Version 
  1.06.</P>

<P>

<HR>

</P>

<P>&copy; David Maddison &amp; Wayne Maddison, 2005</P>
</BODY>
</HTML>

